package mbsl.main;

import org.eclipse.swt.widgets.MenuItem;

public interface MenuBarController {
	/**
	 * Adds a push-style menu item to the specified path, at the end of the parent menu.
	 * <p>
	 * If there is a menu item at this path, the existing item will be returned.
	 * <p>
	 * Mnemonics can be set with an ampersand (&) before the letter which should be the mnemonic.  If you want an
	 * ampersand in the path, double it (&&).  The path separator is //.  Examples of paths:
	 * <pre>
	 * &File//&New//Project
	 * &Help//S&earch
	 * &Edit//&Fit && Finish
	 * </pre>
	 * There is no need to include the ampersands when referencing already existing items.
	 * @see #add(String, int)
	 * @see #add(String, int, int)
	 * @see #remove(String)
	 * @param path The path of the menu item.
	 * @return The new menu item, or the old one if one exists at this path already.
	 */
	public MenuItem add(String path);
	/**
	 * Adds a menu item to the specified path, at the end of the parent menu.
	 * <p>
	 * If there is a menu item at this path, the existing item will be returned.
	 * <p>
	 * Mnemonics can be set with an ampersand (&) before the letter which should be the mnemonic.  If you want an
	 * ampersand in the path, double it (&&).  The path separator is //.  Examples of paths:
	 * <pre>
	 * &File//&New//Project
	 * &Help//S&earch
	 * &Edit//&Fit && Finish
	 * </pre>
	 * There is no need to include the ampersands when referencing already existing items.
	 * <p>
	 * This method takes a style argument, which allows specification of the type of item.
	 * <ul>
	 * <li>For check box, pass SWT.CHECK
	 * <li>For normal style, pass SWT.PUSH
	 * <li>For radio button, pass SWT.RADIO
	 * <li>For a separator, pass SWT.SEPARATOR
	 * </ul>
	 * @see #add(String)
	 * @see #add(String, int, int)
	 * @see #remove(String)
	 * @param path The path of the menu item.
	 * @param type The type of button.  SWT.CHECK, SWT.PUSH, and SWT.RADIO, as well as SWT.SEPARATOR are accepted values.
	 */
	public MenuItem add(String path, int style);
	/**
	 * Adds a menu item to the specified path.  If there is a menu item at this path, the existing item will be returned.
	 * <p>
	 * Mnemonics can be set with an ampersand (&) before the letter which should be the mnemonic.  If you want an
	 * ampersand in the path, double it (&&).  The path separator is //.  Examples of paths:
	 * <pre>
	 * &File//&New//Project
	 * &Help//S&earch
	 * &Edit//&Fit && Finish
	 * </pre>
	 * There is no need to include the ampersands when referencing already existing items.
	 * <p>
	 * This method takes a style argument, which allows specification of the type of item.
	 * <ul>
	 * <li>For check box, pass SWT.CHECK
	 * <li>For normal style, pass SWT.PUSH
	 * <li>For radio button, pass SWT.RADIO
	 * <li>For a separator, pass SWT.SEPARATOR
	 * </ul>
	 * <p>
	 * In addition, this method takes an index argument, which sets where on the parent menu the item should be put.
	 * The index is 0-relative.
	 * @see #add(String)
	 * @see #add(String, int)
	 * @see #remove(String)
	 * @param path The path at which to create this menu item, using // as path separators.
	 * @param type The type of button.  SWT.CHECK, SWT.PUSH, and SWT.RADIO, as well as SWT.SEPARATOR are accepted values.
	 * @param index The index at which to put this button.
	 */
	public MenuItem add(String path, int style, int index);
	/**
	 * Removes this item, all its children, and all empty parents.<p>
	 * Assume the menu tree:
	 * <pre>
	 * People
	 * \-Weasley
	 * | \-Ron
	 * | \-Ginny
	 * \-Malfoy
	 *   \-Lucius
	 * </pre>
	 * removeMenuItem("People//Weasley") would remove the Weasley element and both its children Ron and Ginny.<br>
	 * removeMenuItem("People//Malfoy//Lucius") would remove the Lucius element AND the Malfoy element, since it no longer has any children.<br>
	 * removeMenuItem("People") would remove all elements in this tree.
	 * <p>
	 * For details on path syntax, see add(String).
	 * There is no need to include the ampersands when referencing already existing items.
	 * @see #add(String)
	 * @see #add(String, int)
	 * @see #add(String, int, int)
	 * @param path The path of the menu item.
	 */
	public void remove(String path);
}
